Pular para o conteúdo principal

Troubleshooting

Esta seção fornece orientações sobre como resolver problemas comuns relacionados ao Pix Cash-in e QR Codes.

Pagamento Não Encontrado​

Caso ocorra a busca de um pagamento e ele não seja encontrado do nosso lado, deve ser verificado do lado do pagamento (pagador) se:

  • A transação foi corretamente debitada da conta.
  • A transação foi enviada ao SPI (Sistema de Pagamentos Instantâneos).
  • Não ocorreu o desfazimento da transação do lado do pagador.

Se todas as condições acima forem atendidas e o pagamento ainda não constar em nosso sistema, entre em contato com nosso suporte.

Solução de Problemas do QRCode​

Esta seção descreve os principais erros relacionados ao uso dos endpoints de QRCode, suas possíveis causas e como resolvê-los.

O processamento do QRCode é assíncrono e pode retornar falsos positivos, então um status 200 em algum momento não garante sucesso.

Erros comuns​

1. POST /pix/qrcode/static - Corpo ausente ou vazio​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Corpo da requisição inválido ou malformado"
  ]
}
Causa​

A requisição não incluiu um corpo, mesmo que vazio {}.

Solução​

Certifique-se de enviar um corpo JSON válido, mesmo que vazio.

Exemplo com curl:

curl -X POST https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/static \
  -H "x-delbank-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

2. GET /pix/qrcode/static/:transactionIdentifier - ID inválido ou ausente​

Exemplo​
{
  "title": "Not Found",
  "status": 404
}
Causa​

O transactionIdentifier não pertence à conta, está incorreto ou não foi informado na requisição.

Solução​

Verifique se o transactionIdentifier está correto e pertence à sua conta. Certifique-se de que está incluído no caminho da URL.

3. PATCH /pix/qrcode/static/:transactionIdentifier/cancel - QR Code não encontrado​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "QR_CODE_NOT_FOUND",
  "errors": [
    "QR Code não encontrado"
  ]
}
Causa​

O transactionIdentifier não pertence à conta, está incorreto ou não foi informado na requisição.

Solução​

Verifique se o transactionIdentifier é válido e associado à sua conta. Certifique-se de que está incluído no caminho da URL.

4. POST /pix/qrcode/dynamic - Objeto address incompleto​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Address: Os campos 'cityName', 'zipCode', 'state' devem ser informados"
  ]
}
Causa​

O objeto address está incompleto; campos obrigatórios como 'cityName', 'zipCode', 'state' estão faltando.

Solução​

Forneça todos os campos obrigatórios no objeto address: cityName, zipCode, state, uf, street.

5. POST /pix/qrcode/dynamic - Objeto payer incompleto​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Payer: Os campos 'name' e 'document' devem ser informados"
  ]
}
Causa​

O objeto payer está incompleto; campos obrigatórios como 'name' e 'document' estão faltando.

Solução​

Inclua todos os campos obrigatórios no objeto payer: name, document, validate (opcional).

6. POST /pix/qrcode/dynamic - Valor inválido para formatResponse​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "formatResponse: Valores aceitos: [ONLY_PAYLOAD, PAYLOAD_AND_QRCODE]"
  ]
}
Causa​

O campo formatResponse contém um valor inválido.

Solução​

Use apenas valores aceitos: ONLY_PAYLOAD ou PAYLOAD_AND_QRCODE.

7. POST /pix/qrcode/dynamic - additionalInfos faltando value​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Corpo da requisição inválido ou malformado"
  ]
}
Causa​

No array additionalInfos, um objeto tem "name": "Split" mas falta o atributo "value".

Solução​

Certifique-se de que cada objeto additionalInfos tenha os campos "name" e "value".

8. POST /pix/qrcode/dynamic - additionalInfos faltando name​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "additionalInfos[0].name: não deve estar em branco"
  ]
}
Causa​

No array additionalInfos, um objeto tem "value": "Teste" mas falta o atributo "name".

Solução​

Forneça o campo "name" para cada objeto additionalInfos.

9. POST /pix/qrcode/due-date - taxes sem dueDate​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "taxes: só deve ser informado se dueDate também for informado",
    "dueDate: não deve ser nulo"
  ]
}
Causa​

Taxes foram fornecidas sem especificar dueDate.

Solução​

Inclua dueDate ao fornecer taxes.

10. POST /pix/qrcode/due-date - dueDate ausente​

Exemplo​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "dueDate: não deve ser nulo"
  ]
}
Causa​

O campo dueDate está faltando.

Solução​

Forneça o campo dueDate na requisição.

Lista de Verificação de Diagnóstico​

Antes de abrir um ticket de suporte, verifique:

  • Chave de API correta e headers
  • Corpo JSON válido com todos os campos obrigatórios
  • TransactionIdentifier correto e pertencente à sua conta
  • Processamento assíncrono pode causar atrasos

Informações Úteis para Suporte​

Se precisar abrir um ticket de suporte, forneça:

  • Endpoint usado
  • Corpo da requisição (se aplicável)
  • Timestamp da requisição
  • ID da conta
  • Chave de API (parcial)
  • O log de erro retornado